Occasional Contributor

This role defines a user who browses through the source code of the project and occasionally submits patches. Patches may be submitted in one of two ways:

• Attach a patch file to the JIRA issue

• Creating a pull request on GitHub

The approach a contributor chooses to use depends entirely his/her personal preference, but usually is tied to how the contributor accesses Infinispan's source code. If the contributor directly clones the upstream repository, they should submit patch files. If the contributor instead uses their personal GitHub account to fork the upstream repository, then they are should issue a pull request.

git remote add devA https://github.com/developerA/infinispan.git]

Frequent Contributor

A frequent contributor will only ever submit patches via a pull requests. The pull request will be submitted via GitHub.

Frequent contributors should always fork the upstream project on GitHub and work off a clone of this fork. This is very similar to Creating a pull request on GitHub workflow used by a Occasional Contributor.

Project Admin

Project Admins have a very limited role. Only Project Admins are allowed to push to upstream, and Project Admins never write any code directly on the upstream repository. All Project Admins do is pull in and merge changes from contributors (even if the "contributor" happens to be themselves) into upstream, perform code reviews and either commit or reject such changes.

This approach ensures Infinispan maintains quality on the main code source tree, and allows for important code reviews to take place again ensuring quality. Further, it ensures clean and easily traceable code history and makes sure that more than one person knows about the changes being performed.

$ git log --pretty=oneline --graph --abbrev-commit  # History messed up due to a bad merge
*   3005020 Merge branch 'ISPN-786' of git://github.com/Sanne/infinispan
|\ 
| * e757265 ISPN-786 Make dependency to log4j optional  <-- Same with cb4e5d6 - unnecessary
* | cb4e5d6 ISPN-786 Make dependency to log4j optional  <-- Cherry-picked commit by other admin
|/
* ...

$ git reset cb4e5d6  # revert the bad merge

Release branches

Infinispan has 4 main release branches.  These are master (ongoing work on the 5.0.x series), 4.2.x (ongoing work on the 4.2.x series), 4.1.x and 4.0.x (respective maintenance branches). Work should never be committed directly to any of these release branches; topic branches should always be used for work, and these topic branches should be merged in.

Topic branches

Some of the biggest features of git are speed and efficiency of branching, and accuracy of merging. As a result, best practices involve making frequent use of branches. Creating several topic branches a day, even, should not be considered excessive, and working on several topic branches simultaneously again should be commonplace.

Chapter 3, Section 4 of Pro Git has a detailed discussion of topic branches. For Infinispan, it makes sense to create a topic branch and name it after the JIRA it corresponds to. (if it doesn't correspond to a JIRA, a simple but descriptive name should be used).

Comments

It is extremely important that comments for each commit are clear and follow certain conventions. This allows for proper parsing of logs by git tools. Read this article on how to format comments for git and adhere to them. Further to the recommendations in the article, the short summary of the commit message should be in the following format:

ISPN-XXX - Subject line of the JIRA in question

This should be followed by a detailed explanation of the commit.  Why it was done, how much of it. was completed, etc. You may wish to express this as a list, for example:

* Add a unit test
* Add more unit tests
* Fix regressions
* Solve major NP-Complete problems

Commits

Sometimes work on your topic branch may include several commits. For example, committing a test. Then committing another test. Then perhaps committing a fix. And perhaps fixing the fix in the next commit . Before issuing a pull request for this topic branch, consider cleaning up these commits. Interactive rebasing helps you squash several commits into a single commit, which is often more coherent to deal with for others merging in your work. Chapter 6, Section 4 of Pro Git has details on how to squash commits and generally, clean up a series of commits before sharing this work with others.

Also, it is important to make sure you don't accidentally commit files for which no real changes have happened, but rather, whitespace has been modified. This often happens with some IDEs. git diff --check should be run before you issue such a pull request, which will check for such "noise" commits and warn you accordingly. Such files should be reverted and not be committed to the branch.

Further, adhering to Infinispan's code style guidelines will help minimise "noise" commits. Project Admins should feel free to ask contributors to reformat their code if necessary.

If you have cloned upstream

If you have a clone of the upstream, you may want to update it from time to time. Running:

$ git fetch origin
$ git fetch origin --tags

will often do the trick. You could then pull the specific branches you would need to update:

$ git checkout master
$ git pull origin master
$ git checkout 4.2.x
$ git pull origin 4.2.x

$ git checkout <topic>_master
$ git rebase master

$ git checkout topic_4.2.x
$ git rebase 4.2.x

If you have forked upstream

If you have a fork of upstream, you should probably define upstream as one of your remotes:

$ git remote add upstream git://github.com/infinispan/infinispan.git

You should now be able to fetch and pull changes from upstream into your local repo, though you should make sure you have no uncommitted changes. (You do use topic branches, right?)

$ git fetch upstream
$ git fetch upstream --tags
$ git checkout master
$ git pull upstream master
$ git push origin master
$ git checkout 4.2.x
$ git pull upstream 4.2.x
$ git push origin 4.2.x

A script can do this for you - have a look at sync_with_upstream.

$ git checkout topic_master
$ git rebase master

$ git checkout topic_4.2.x
$ git rebase 4.2.x

Auto-completions

Save this script as /.git-completion.bash _{and in} /.bash_profile, add the following on one line:

source ~/.git-completion.bash

After logging out and back in again, typing git <TAB> will give you a list of git commands, as would git c<TAB>, etc. This even works for options, e.g. git commit --<TAB>. The completions are even aware of your refs, so even git checkout my_br<TAB> will complete to git checkout my_branch!

Note that you get git autocompletion for free if you use zsh instead of bash.

Terminal colours

Add the following to your ~/.gitconfig

[color]
    ui = yes
[color "branch"]
     current = yellow reverse
     local = yellow
     remote = green
[color "diff"]
     meta = yellow bold
     frag = magenta bold
     old = red bold
     new = green bold
[color "status"]
     added = yellow
     changed = green
     untracked = cyan

Aliases

Some git commands are pretty long to type, especially with various switches. Aliases help you to map shortcuts to more complex commands.; Again, For example, add the followin to ~/.gitconfig:

[alias]
     co = checkout
     undo = reset --hard
     cb = checkout -b
     br = branch
     cp = cherry-pick
     st = status
     l = log --pretty=oneline --decorate --abbrev-commit
     lg = log --decorate --abbrev-commit
     last = log --decorate -1 -p --abbrev-commit
     ci = commit -a
     pom = push origin master
     graph = log --pretty=oneline --graph --abbrev-commit
     dt = difftool

Visual History

Git ships with gitk, a GUI that visually represents a log. If you use Mac OS X, GitX is a good alternative. Try typing gitk or gitx in a git project directory.

Visual diff and merge tools

There are several options available, including KDiff3, meld and Perforce's P4Merge which are all either open source or available for free. See this link on setting these up (section under External Merge and Diff Tools)

Choosing an Editor

You can customise the editor used by git editing ~/.gitconfig. The following fires up MacVIM instead of the default vi editor:

[core]
     editor = mvim -f

Alternatively, you could fire up TextMate or another editors of your choice.

Shell prompt

You can change your Bash shell prompt to print the current repository's branch name. Add the following to your ~/.bashrc:

function git_current_branch {
  git branch --no-color 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/[\1]/'
}

if [ "$PS1" ]; then
  PS1='[\u@\h:\W]$(git_current_branch)\$ '
fi

The resulting shell prompt will look like:

trustin@matrix:infinispan-4.2][4.2.x]$

If you're a ZSH user, you can get even more interesting branch information thanks to this blog post, such as:

• whether your branch is dirty (⚡)

• whether it's ahead of the remote(↑)

• whether it diverges with the remote (↕)

• whether it's behind (↓)

For example, the following prompt indicates that the current branch is 't_ispn775_master' and that the branch is dirty:

~/Go/code/infinispan.git]% (t_ispn775_master⚡)